fix(query-core): avoid throwing promise errors when data exists #10025

HyeongSeoku · 2026-01-09T16:23:12Z

🎯 Changes

Aligns experimental_prefetchInRender promise rejection behavior with Suspense defaults.
When data already exists, errors no longer reject the thenable and therefore do not trigger the Error Boundary (e.g. subsequent pages in useInfiniteQuery).
Adds a regression test for the infinite query + promise path.

🧠 Motivation

useSuspenseInfiniteQuery only throws to the Error Boundary when there is no data to show. However, useInfiniteQuery combined with experimental_prefetchInRender was rejecting the promise even when data existed (e.g. page 2 fetch errors), which made Error Boundary appear unexpectedly. This change makes both paths consistent.

🔧 Implementation Notes

Core behavior updated in packages/query-core/src/queryObserver.ts.
Test added in packages/react-query/src/__tests__/useQuery.promise.test.tsx to ensure refetch/page errors with existing data do not throw to Error Boundary.

🧪 Testing

pnpm --filter @tanstack/react-query test:lib

✅ Checklist

Followed contributing guidelines
Tests run locally

📷 Optional Evidence

Before: fetch next page error triggers Error Boundary
After: fetch next page error does not trigger Error Boundary; isFetchNextPageError: true is shown

Summary by CodeRabbit

Bug Fixes
- Fixed prefetch promise rejection handling to align with Suspense behavior, ensuring errors trigger error boundaries only when no data is available, rather than on every error occurrence.
- Improved error state handling for infinite query pagination to prevent unnecessary error boundary activation during fetch operations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

…te query

changeset-bot · 2026-01-09T16:23:17Z

🦋 Changeset detected

Latest commit: 054149f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@tanstack/query-core	Patch
@tanstack/angular-query-experimental	Patch
@tanstack/query-async-storage-persister	Patch
@tanstack/query-broadcast-client-experimental	Patch
@tanstack/query-persist-client-core	Patch
@tanstack/query-sync-storage-persister	Patch
@tanstack/react-query	Patch
@tanstack/solid-query	Patch
@tanstack/svelte-query	Patch
@tanstack/vue-query	Patch
@tanstack/angular-query-persist-client	Patch
@tanstack/react-query-persist-client	Patch
@tanstack/solid-query-persist-client	Patch
@tanstack/svelte-query-persist-client	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/solid-query-devtools	Patch
@tanstack/svelte-query-devtools	Patch
@tanstack/vue-query-devtools	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-01-09T16:23:24Z

📝 Walkthrough

Walkthrough

The PR fixes error boundary behavior in useInfiniteQuery with experimental_prefetchInRender by aligning promise rejection logic to only throw when data is unavailable, matching useSuspenseInfiniteQuery behavior for subsequent pages.

Changes

Cohort / File(s)	Summary
Changeset Documentation `.changeset/fix-prefetch-error-boundary.md`	New patch release note documenting alignment of experimental_prefetchInRender promise rejection behavior with Suspense to only throw when no data is available.
Core Query Logic `packages/query-core/src/queryObserver.ts`	Introduces guards (`hasResultData`, `isErrorWithoutData`) to differentiate error-with-data vs. error-without-data scenarios. Adjusts `finalizeThenableIfPossible` to reject only when error lacks data. Updates thenable lifecycle conditions in prefetch path to prevent unnecessary recreation when errors have existing data.
Test Coverage `packages/react-query/src/__tests__/useQuery.promise.test.tsx`	Adds test case validating that error boundary is not triggered for refetch errors on subsequent pages in infinite queries, ensuring `isFetchNextPageError` is set without error boundary invocation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

fix(core): observing "promise" needs to implicitly observe "data" #9772: Both modify queryObserver's handling of query.promise and thenable state tracking.
fix(core): do not reject promise right away - only when promise gets used #9576: Both adjust queryObserver promise rejection conditions for prefetchInRender behavior.

Suggested labels

package: react-query, package: query-core

Suggested reviewers

TkDodo

Poem

🐰 A rabbit hops through query streams so fine,
Where promises reject with perfect line—
No more false bounds when data's safe and sound,
Just errors dance where they're truly found! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main fix: avoiding throwing promise errors when data exists, which directly addresses the core issue.
Description check	✅ Passed	The PR description comprehensively covers changes, motivation, implementation details, testing, and includes completed checklist items; all key sections are present and well-documented.
Linked Issues check	✅ Passed	The PR successfully addresses issue #9938 by aligning error boundary behavior between useInfiniteQuery + experimental_prefetchInRender and useSuspenseInfiniteQuery, with core logic fixes and regression tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the inconsistent error boundary behavior in infinite queries; no unrelated modifications detected in the changeset, core logic, or tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f616474 and cf7059e.

📒 Files selected for processing (3)

.changeset/fix-prefetch-error-boundary.md
packages/query-core/src/queryObserver.ts
packages/react-query/src/__tests__/useQuery.promise.test.tsx

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-11-22T09:06:05.219Z

Learnt from: sukvvon
Repo: TanStack/query PR: 9892
File: packages/solid-query-persist-client/src/__tests__/PersistQueryClientProvider.test.tsx:331-335
Timestamp: 2025-11-22T09:06:05.219Z
Learning: In TanStack/query test files, when a queryFn contains side effects (e.g., setting flags for test verification), prefer async/await syntax for clarity; when there are no side effects, prefer the .then() pattern for conciseness.

Applied to files:

.changeset/fix-prefetch-error-boundary.md
packages/react-query/src/__tests__/useQuery.promise.test.tsx
packages/query-core/src/queryObserver.ts

🧬 Code graph analysis (1)

packages/react-query/src/__tests__/useQuery.promise.test.tsx (1)

packages/query-core/src/queryObserver.ts (1)

query (700-717)

🔇 Additional comments (6)

.changeset/fix-prefetch-error-boundary.md (1)

1-5: LGTM! Clear and concise changeset.

The changeset appropriately describes the patch-level fix and clearly communicates the behavioral alignment.

packages/query-core/src/queryObserver.ts (4)

595-596: LGTM! Clear guard conditions.

The hasResultData and isErrorWithoutData guards cleanly distinguish between error-with-data (subsequent page errors) and error-without-data (initial load errors), which is the core of this fix.

597-603: LGTM! Correct promise finalization logic.

The updated logic ensures the thenable only rejects when there's an error without data to show, and resolves with data when available. This correctly prevents Error Boundary triggers for subsequent page errors in infinite queries.

627-629: LGTM! Correct recreation logic for fulfilled state.

Properly handles the transition from fulfilled to error-without-data by recreating the thenable, while also recreating when data changes. This ensures the promise state accurately reflects the query state.

632-634: LGTM! Correct recreation logic for rejected state.

Properly handles the transition from rejected to data-available state by recreating the thenable to resolve with data. Also correctly recreates when the error changes. This ensures error-with-data scenarios don't keep the promise rejected.

packages/react-query/src/__tests__/useQuery.promise.test.tsx (1)

1432-1497: LGTM! Comprehensive regression test.

This test effectively validates the fix by:

Setting up an infinite query with successful first page and failing subsequent page

Verifying that fetchNextPage errors surface as isFetchNextPageError: true

Asserting the Error Boundary is NOT triggered when data exists

The test directly covers the issue described in #9938 and ensures the behavior now aligns with useSuspenseInfiniteQuery.

Based on learnings, the test correctly uses async/await in the queryFn as it contains side effects (throwing errors based on pageParam).

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

nx-cloud · 2026-01-16T10:38:29Z

View your CI Pipeline Execution ↗ for commit 054149f

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	3m 56s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1s	View ↗

☁️ Nx Cloud last updated this comment at 2026-01-16 10:42:57 UTC

pkg-pr-new · 2026-01-16T10:40:53Z

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@10025

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@10025

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@10025

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@10025

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@10025

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@10025

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@10025

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@10025

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@10025

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@10025

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@10025

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@10025

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@10025

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@10025

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@10025

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@10025

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@10025

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@10025

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@10025

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@10025

commit: 054149f

sentry · 2026-01-16T10:44:20Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.62%. Comparing base (4e8be3f) to head (054149f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main   #10025       +/-   ##
===========================================
+ Coverage   45.84%   59.62%   +13.77%     
===========================================
  Files         200      129       -71     
  Lines        8526     5738     -2788     
  Branches     1983     1578      -405     
===========================================
- Hits         3909     3421      -488     
+ Misses       4157     2000     -2157     
+ Partials      460      317      -143

Components	Coverage Δ
@tanstack/angular-query-experimental	`93.85% <ø> (ø)`
@tanstack/eslint-plugin-query	`∅ <ø> (∅)`
@tanstack/query-async-storage-persister	`43.85% <ø> (ø)`
@tanstack/query-broadcast-client-experimental	`24.39% <ø> (ø)`
@tanstack/query-codemods	`∅ <ø> (∅)`
@tanstack/query-core	`97.37% <100.00%> (-0.01%)`	⬇️
@tanstack/query-devtools	`3.38% <ø> (ø)`
@tanstack/query-persist-client-core	`80.00% <ø> (ø)`
@tanstack/query-sync-storage-persister	`84.61% <ø> (ø)`
@tanstack/query-test-utils	`∅ <ø> (∅)`
@tanstack/react-query	`96.73% <ø> (ø)`
@tanstack/react-query-devtools	`9.25% <ø> (ø)`
@tanstack/react-query-next-experimental	`∅ <ø> (∅)`
@tanstack/react-query-persist-client	`100.00% <ø> (ø)`
@tanstack/solid-query	`77.81% <ø> (ø)`
@tanstack/solid-query-devtools	`64.17% <ø> (ø)`
@tanstack/solid-query-persist-client	`100.00% <ø> (ø)`
@tanstack/svelte-query	`∅ <ø> (∅)`
@tanstack/svelte-query-devtools	`∅ <ø> (∅)`
@tanstack/svelte-query-persist-client	`∅ <ø> (∅)`
@tanstack/vue-query	`71.91% <ø> (ø)`
@tanstack/vue-query-devtools	`∅ <ø> (∅)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-01-16T11:03:32Z

🎉 This PR has been released!

@tanstack/[email protected]

Thank you for your contribution!

HyeongSeoku added 3 commits January 8, 2026 13:53

fix(query-core): avoid throwing promise errors when data exists

a423b3e

test(react-query): cover refetch error behavior with promise + infini…

1619331

…te query

chore(changeset): add query-core patch for prefetch error handling

cf7059e

github-actions bot added package: react-query package: query-core labels Jan 9, 2026

HyeongSeoku mentioned this pull request Jan 9, 2026

useInfiniteQuery + experimental_prefetchInRender uses error boundary for subsequent pages #9938

Closed

Merge branch 'main' into fix/9938

054149f

TkDodo approved these changes Jan 16, 2026

View reviewed changes

TkDodo merged commit dea1614 into TanStack:main Jan 16, 2026
7 checks passed

github-actions bot mentioned this pull request Jan 16, 2026

ci: Version Packages #10045

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(query-core): avoid throwing promise errors when data exists #10025

fix(query-core): avoid throwing promise errors when data exists #10025

HyeongSeoku commented Jan 9, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 9, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Jan 16, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 16, 2026

Uh oh!

Uh oh!

sentry bot commented Jan 16, 2026

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

fix(query-core): avoid throwing promise errors when data exists #10025

fix(query-core): avoid throwing promise errors when data exists #10025

Conversation

HyeongSeoku commented Jan 9, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

🧠 Motivation

🔧 Implementation Notes

🧪 Testing

✅ Checklist

📷 Optional Evidence

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

nx-cloud bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 16, 2026

Uh oh!

Uh oh!

sentry bot commented Jan 16, 2026

Codecov Report

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

HyeongSeoku commented Jan 9, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

coderabbitai bot commented Jan 9, 2026 •

edited

Loading

nx-cloud bot commented Jan 16, 2026 •

edited

Loading